Document Number EDCS-456333
Based on Template EDCS-127523 Rev 1.0
Created By Santosh Ransubhe

Cisco Systems

 

Seadragon 

AVVID XML Layer (AXL) API

Interface Specification

Reviewers

 

Department

Name

Program Management Bill Forsythe (Mgr,Software Development)
QA  
Documentation  
Engineering* Jerry Vander Voord
Developer Support Santosh Ransubhe

  

Modification History

Rev.

Date

Originator

Comment

1

6/8/2005

Santosh Ransubhe

Initial Version

2

7/12/2005

Santosh Ransubhe

Review comments incorporated in sections 18.2 and 21.0.

3

20/01/2006

Santosh Ransubhe

Latest changes incorporated in section 5.2

 

 

 

TABLE OF CONTENTS

1.0 PURPOSE

2.0 SCOPE

3.0 DEFINITIONS/GLOSSARY

4.0 CONCEPT/OVERVIEW

5.0 SUMMARY OF CHANGES FROM PREVIOUS RELEASE/WHAT’S NEW

5.1 Changes for 4.1.3

5.2 Changes for Seadragon(5.0)

6.0 SUMMARY OF REQUIREMENTS ADDRESSED

7.0 RESOLVED SEVERITY 6 DEFECTS

8.0 MESSAGE/INTERFACE COMPLIANCE SUMMARY/SUPPORT MATRIX

9.0 CAVEATS

10.0 PLATFORM CONSIDERATIONS

11.0 LOWER LAYER TRANSPORT PROTOCOL IMPLICATIONS

12.0 MESSAGE/INTERFACE DEFINITION

13.0 MESSAGE SEQUENCE CHARTS

13.1 Example Message Sequence Chart

14.0 PERFORMANCE AND SCALABILITY

15.0 PACKAGING

16.0 LICENSING CONSIDERATIONS

17.0 OPERATIONS, ADMINISTRATION, AND MAINTENANCE (OA&M)

18.0 SECURITY

19.0 INTEGRATION CONSIDERATIONS AND INTER-OPERABILITY

20.0 PATENTABILITY

21.0 TROUBLESHOOTING

21.1 Error Codes

21.2 Other Troubleshooting Information

22.0 OPEN ISSUES/RISKS/DEPENDENCIES

23.0 REFERENCE DOCUMENTS

24.0 SAMPLE CODE (OPTIONAL)

25.0 ATTACHMENTS

25.1 Document Review Action Item

 

1.0 Purpose

The AVVID XML Layer (AXL) Application Programming Interface (API) provides a mechanism for inserting, retrieving, updating, and removing data from the database using an eXtensible Markup Language (XML) Simple Object Access Protocol (SOAP) interface. This allows a programmer to access Cisco CallManager data using XML and receive the data in XML form, instead of using a binary library or DLL.

The AXL API methods, known as requests, are performed using a combination of HTTPS and SOAP.  SOAP is an XML remote procedure call protocol.  Users perform requests by sending XML data to the Cisco CallManager server.  The server then returns the AXL response, which is also a SOAP message.

Target Audience for this Guide

This programming guide is designed for fairly experienced developers who would like access to one or more of the following items:

·         Cisco CallManager data

·         Cisco CallManager data in XML format

·         Cisco CallManager data in a platform-independent manner

This guide assumes the developer has knowledge of a high-level programming language such as C++, Java, or an equivalent language. The developer must also have knowledge or experience in the following areas:

·         TCP/IP Protocol

·         Hypertext Transport Protocol

·         Socket programming

·         XML

 

In addition, the users of the AXL API and this programming guide must have a firm grasp of XML Schema, which was used to define the AXL requests, responses, and errors.  For more information on XML Schema, please refer to http://www.w3.org/TR/xmlschema-0/.

*     Caution

The AXL API gives enormous power to developers to modify the CallManager system database. The developer must take caution when using AXL, since each API call impacts the system. Abuse of the API can lead to dropped calls and slower system performance.  AXL is not intended as a real-time API, but as a provisioning and configuration API.

2.0 Scope

3.0 Definitions/Glossary

4.0 Concept/Overview

5.0 Summary Of Changes From Previous Release/What’s New

The following new API calls were added for Skate (CCM 4.1):

Note:  The following API calls have changed since the previous release. It is possible that these changes might require changes to existing user code which is making use of them:
  • addPhone
  • updatePhone
  • getPhone
  • addLine
  • updateLine
  • addUser
  • removeUser
  • updateUser
  • getUser
  • addDeviceProfile
  • updateDeviceProfile
  • getDeviceProfile
  • addRoutePattern
  • updateRoutePattern
  • getRoutePattern
  • addRouteList
  • updateRouteList
  • getRouteList
  • addGatewayEndpoint
  • updateGatewayEndpoint
  • getGatewayEndpoint
  • addH323Trunk
  • updateH323Trunk
  • removeH323Trunk
  • getH323Trunk
  • addHuntPilot
  • updateHuntPilot
  • removeHuntPilot
  • getHuntPilot
  • addProcessNode
  • updateProcessNode
  • removeProcessNode
  • getProcessNode
  • listAllProcessNodes
  • listProcessNodesByService
  • addRoutePartition
  • updateRoutePartition
  • removeRoutePartition
  • getRoutePartition
  • addH323Gateway
  • updateH323Gateway
  • removeH323Gateway
  • getH323Gateway
  • addH323Phone
  • updateH323Phone
  • removeH323Phone
  • getH323Phone
  • addHuntList
  • updateHuntList
  • removeHuntList
  • getHuntList

5.1 Changes for 4.1.3

The following API calls have been changed in 4.1.3 as part of Pickup and iREC Enhancements:

5.2 Changes for Seadragon(5.0)

The following API calls have been changed in 5.0:
Note: Some of the fields which were removed from Seadragon database have been deprecated in AXL. Annotation has been added for such fields.
The following API calls have been added in 5.0:
The following API calls have been deprecated in 5.0:

6.0 Summary of Requirements Addressed

Provide a cross-platform XML interface to the CallManager database.

7.0 Resolved Severity 6 Defects

  • CSCsb00250 : AXL enhancements for user authentication.

    8.0 Message/Interface Compliance Summary/Support Matrix

    Compliance with XML Schema 1.0.  XML Schema compliance was tested with a 3rd party application called XML Spy version 4.x.  Early versions of MSXML schema validator did not support enough of the XML Schema 1.0 recommendation to be used.

    AXL complies with SOAP 1.1 as defined by the World Wide Web Consortium.

    Compliance with HTTPS 1.1.

    9.0 Caveats

    10.0 Platform Considerations

    There are no platform considerations. The client is only required to be able to send an HTTPS request to the AXL endpoint.

    11.0 Lower Layer Transport Protocol Implications

    The AXL API runs as an independent service and can only be accessed via HTTPS.

    12.0 Message/Interface Definition

    12.1 Legend

    The AXL schema is attached as an HTML document (see section 12.2), which graphically describes each request and response.  The following legend explains the graphics used in the schema document.

     

    Request or Response

    Element Name

    Description

     

    Complex Element

     

    Complex Element

    A complex element can have child elements, as well as attributes. An element with a solid border is required to appear in an XML instance document.

     

    Simple Element

     

    Simple Element

    A simple element cannot have child elements but can have attributes. An element with a solid border is required to appear in an XML instance document.

     

    Optional Element

     

    Optional Element

    An optional element is not required to appear in an instance of the XML. Any type of element can be optional, including sequence and choice elements.

     

    Sequence

     

    Sequence Element

    A sequence means that all children of this element must appear in the XML in the order that they are listed.

     

    Choice Element

     

    Choice Element

    A choice element means that only one of the children of this element can appear in the XML.

    12.2 Individual Message Defiitions

    Individual messages are defined here.

    13.0 Message Sequence Charts

    Message Sequence Chart

    14.0 Performance and Scalability

    Throttling of Requests

    The side-effects of updating the Cisco CallManager database can adversely affect system performance; therefore, the system administrator is capable of controlling how many AXL requests are allowed to update the database per minute.  This value is controlled via the Database Layer service parameter “MaxAXLWritesPerMinute”.

    AXL accommodates all requests until the “MaxAXLWritesPerMinute” value is reached. Subsequent attempts to modify the database with AXL will be rejected with an HTTPS 503 Service Unavailable response.  Every minute, AXL will reset its internal counter and begin to accept AXL update requests until the limit is reached again.

    The following AXL request are considered "Reads" and do not count against the "MaxAXLWritesPerMinute" service parameter. All other AXL requests not in this list count against the service parameter:

    15.0 Packaging

    N/A.

    16.0 Licensing Considerations

    N/A.

    17.0 Operations, Administration, and Maintenance (OA&M)

    18.0 Security

    18.1 Authentication

    Anonymous access to the AXL SOAP service should be deactivated to enforce user authentication.  User authentication is controlled via the HTTPS Basic Authentication scheme. Therefore, you must include the Authorization header in the HTTPS Header.

    For example, if the user agent wishes to send the userid "larry" and password "curly and moe", it would use the following header field:

    Authorization: Basic bGFycnk6Y3VybHkgYW5kIG1vZQ==

    Where the string "bGFycnk6Y3VybHkgYW5kIG1vZQ==" is the Base 64 encoding of "larry:curly and moe".

    18.2 Data Encryption

    AXL SOAP messages should be encrypted using HTTP SSL.

    SSL is functional on the web server by default.  AXL requests are made using the “https” protocol.

    19.0 Integration considerations and Inter-operability

    The AXL API gives enormous power to developers to modify the CallManager system database. The developer must take caution when using AXL, since each API call impacts the system. Abuse of the API can lead to dropped calls and slower system performance.  AXL is not intended as a real-time API, but as a provisioning and configuration API.

    If AXL is determined to be using too much of the CPU time, consider lowering the MaxAXLWritesPerMinute service parameter (see section 14).  If this does not solve the problem, consider purchasing a second server to be used only by applications using AXL.

    20.0 Patentability

    21.0 Troubleshooting

    21.1 Error Codes

    If an exception occurs on the server, or if any other error occurs during the processing of an AXL request, then an error is returned in the form of a SOAP Fault message:

    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"  
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <SOAP-ENV:Body>
            <SOAP-ENV:Fault>
                <faultcode>SOAP-ENV:Client</faultcode>
                <faultstring>
                <![CDATA[
                An error occurred during parsing
                Message: End element was missing the character '>'.
     
                Source = Line : 41, Char : 6
                Code : c00ce55f, Source Text : </re
                ]]>
                </faultstring>
            </SOAP-ENV:Fault>
        </SOAP-ENV:Body>

    </SOAP-ENV:Envelope>

     

    SOAP Fault messages can also contain more detailed information.  The following is an example of a detailed SOAP Fault.

    <SOAP-ENV:Envelope  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" S
    OAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
        <SOAP-ENV:Body>
            <SOAP-ENV:Fault>
                <faultcode>SOAP-ENV:Client</faultcode>
                <faultstring>Device not found with name SEP003094C39708.</faultstring>
                <detail  xmlns:axl="http://www.cisco.com/AXL/1.0" 
                         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
                         xsi:schemaLocation="http://www.cisco.com/AXL/1.0 
                                             http://myhost/CCMApi/AXL/V1/axlsoap.xsd">
                    <axl:error  sequence="1234">
                        <code>0</code>
                        <message>
    <![CDATA[
    Device not found with name SEP003094C39708.
    ]]>
                       </message>
                       <request>doDeviceLogin</request>
                   </axl:error>
               </detail>
            </SOAP-ENV:Fault>
        </SOAP-ENV:Body>

    </SOAP-ENV:Envelope>

     

    Error codes will be included in the <detail> element of a SOAP Fault. The errors are represented by the axl:Error element.  If a response to a request contains an <error> element, the user agent can determine the cause of the error by looking at the sub-elements of the <error> tag.  

    The following list describes the <error> element.

    ·         code

    The <code> element is a numerical value that is used by the user agent to find out what type of error has occurred. The error codes are as follows:

    Less than 5000:  These are errors that directly correspond to DBL Exception error codes. AXL will return an explanation for this error in the <message> element.

    5000:    Unknown Error:  An unknown error occurred while processing the request.  This can be due to a problem on the server, but can also be caused by errors in the request.

    5002:    Unknown Request Error: This error occurs if the user agent submits a request that is unknown to the API.

    5003:    Invalid Value Exception: This error occurs if an invalid value is detected in the XML request.

    5007:    Item Not Valid Error: This error occurs if no records are found in the database.

    ·         message

    The <message> element is provided so that the user agent gets a detailed error message explaining the error.  

    ·         request

    The <request> element is provided so that the user agent can determine what type of request generated this error.  This element is optional; therefore it may not always appear.

    22.0 Open Issues/Risks/Dependencies

    23.0 Reference Documents

    24.0 Sample Code (Optional)

    The following examples describe how to make an AXL request and read back the response to the request.  Each SOAP request must be sent to the web server via an HTTPS POST.  The endpoint URL represent the AXL web service running on Cisco CallManger server.   The following list contains the only four required HTTPS headers.

    ·         POST :8443/axl/

    The first header identifies that this particular POST is intended for the Cisco AXL Web Service.  The AXL API only responds to the POST method.

    ·         content-type: text/xml

    The second header confirms that the data being sent to AXL is XML.  If this header is not found then an HTTP 415 error is returned to the client.

    ·         Authorization: Basic <some Base 64 encoded string>

    The third header is the Base64 encoding of the user name and password for the administrator of the AXL Server.  If authentication of the user fails, then an HTTP 401 Access Denied error is returned to the client.

    ·         content-length: <a positive integer>

    The fourth header is the length (in bytes) of the AXL request.

    Note:  Currently, the content-length cannot exceed 40 kilobytes.  If a request is received, which is greater than 40 kilobytes, then an HTTP 413 error message is returned.

     

    The following example contains an HTTPS header for an AXL SOAP request:

    POST :8443/axl
    Host: axl.myhost.com:80
    Accept: text/*
    Authorization: Basic bGFycnk6Y3VybHkgYW5kIG1vZQ==
    Content-type: text/xml
    Content-length: 613
     

    The following AXL request will be used in the code examples displayed in the following sections.  This is an example of a getPhone request:

    POST :8443/axl
    Host: axl.myhost.com:80
    Accept: text/*
    Authorization: Basic bGFycnk6Y3VybHkgYW5kIG1vZQ==
    Content-type: text/xml

    Content-length: 613

     

    <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

        <SOAP-ENV:Body>

            <axl:getPhone xmlns:axl="http://www.cisco.com/AXL/1.0" xsi:schemaLocation="http://www.cisco.com/AXL/1.0 http://ccmserver/schema/axlsoap.xsd"  sequence="1234">

                <phoneName>SEP222222222245</phoneName>

            </axl:getPhone>

        </SOAP-ENV:Body>

    </SOAP-ENV:Envelope>

     

    24.1          C/C++ Example

    This code example uses a hard-coded AXL request and sends it to the AXL Server running on the local system (localhost).  It then reads the response back, outputting the response to the screen.

    #include <winsock2.h>           // required for sockets

    #include <iostream>             // required for console I/O

    #include <sstream>

    #include <string>               // required for std::string

     

    using namespace std;

     

     

    int main(int argc, char* argv[])

    {

    // make connection to server

     

    WSADATA WSAData;

     

    // initialize sockets

    if (int iError = WSAStartup (MAKEWORD(2,0), &WSAData))

    {

           cout << "Windows Sockets startup error. Aborting." << endl;

           return -1;

    }

     

    SOCKET Socket = socket (AF_INET, SOCK_STREAM, IPPROTO_TCP);  

    if (Socket == INVALID_SOCKET)

    {

           cout << "Socket creation error. Aborting." << endl;

           return -1;

    }

     

    SOCKADDR_IN sinRemote;

     

    sinRemote.sin_family = AF_INET;

    sinRemote.sin_port = htons (80) ;

    sinRemote.sin_addr.s_addr =  inet_addr( "127.0.0.1" );

     

    cout << "connecting to service" << endl;

    int retval = connect(Socket, (SOCKADDR *)&sinRemote, sizeof (sinRemote));

                 

    if (retval != 0)

    {

           cout << "Error occured while connecting to socket. Aborting." << endl;

           closesocket(Socket);

           return -1;

    }

    const int BUFSIZE = 2048;

    char buff[BUFSIZE];           // the temporary receive buffer

    string strHTTPHeader;         // the HTTPS Header

    string strAXLRequest;         // the AXL SOAP request

     

    // The AXL request:  getPhone

    strAXLRequest = “<SOAP-ENV:Envelope xmlns:SOAP- \ ENV=\”http://schemas.xmlsoap.org/soap/envelope/\” \ xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" \ xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\"> \

    <SOAP-ENV:Body> \

    <axl:getPhone xmlns:axl=\"http://www.cisco.com/AXL/1.0\" \ xsi:schemaLocation=\"http://www.cisco.com/AXL/1.0 \ http://ccmserver/schema/axlsoap.xsd\" sequence=\"1234\"> \

    <phoneName>SEP222222222245</phoneName> \

    </axl:getPhone> \

    </SOAP-ENV:Body> \

    </SOAP-ENV:Envelope>”;

     

    // temporarily use the buffer to store the length of the request

    sprintf(buff, “%d”, strAXLRequest.length());

     

    // build the HTTPS header  

    strHTTPHeader = "POST :8443/axl\r\n \

    Host: localhost:80\r\n \

    Authorization: Basic bGFycnk6Y3VybHkgYW5kIG1vZQ==\r\n \

    Accept: text/*\r\n \

    Content-type: text/xml\r\n \

    Content-length: ";

     

    strHTTPHeader += buff;

    strHTTPHeader += “\r\n\r\n”;

    // put the HTTPS header and SOAP XML together

    strAXLRequest = strHTTPHeader + strAXLRequest;

     

    // send these bytes to the socket

    retval = send (Socket, strAXLRequest.c_str(),strAXLRequest.length(), 0);  

    if ( retval != SOCKET_ERROR)

    {

           // output response

           cout << "received response: " << endl;

     

           int iTotalRead = 0;

           // read BUFSIZE at a time, writing to another ostringstream  

           do {

                  iNumRead = recv (Socket, buff, BUFSIZE-1, 0);

                  buff[iNumRead] = NULL;

     

                  cout << buff;

                  iTotalRead += iNumRead;

                 

           } while (iNumRead == BUFSIZE-1);

     

           cout << "Read " << iTotalRead << " bytes." << endl;

          

    }

    else

    {

           cout << "An error occured while sending the data to socket." << endl;

    }

     

    // all finished, close socket

     closesocket(Socket);

    return 0;    

    }

     

    24.2          Java Example

    This code example uses a hard-coded AXL request and sends it to the AXL Server running on the local system (localhost).  It then reads the response back, outputting the response to the screen.

    import java.io.*;

    import java.net.*;

     

    public class main

    {

    public static void main(String[] args)

    {

           //Declare references

           String sAXLSOAPRequest = null;        // will hold the complete request,

                                                  // HTTPS header and SOAP payload

     

           String sAXLRequest = null;            // will hold only the SOAP payload

          

           Socket socket = null;                 // socket to AXL server

           OutputStream out = null;              // output stream to server

           InputStream in = null;                // input stream from server

           byte[] bArray = null;                 // buffer for reading response from server

          

           // Build the HTTPS Header

           sAXLSOAPRequest = "POST :8443/axl\r\n";

           sAXLSOAPRequest += "Host: localhost:80\r\n";

           sAXLSOAPRequest += "Authorization: Basic bGFycnk6Y3VybHkgYW5kIG1vZQ==\r\n";

           sAXLSOAPRequest += "Accept: text/*\r\n";

           sAXLSOAPRequest += "Content-type: text/xml\r\n";

           sAXLSOAPRequest += "Content-length: ";

          

           // Build the SOAP payload

           sAXLRequest = "<SOAP-ENV:Envelope xmlns:SOAP-ENV=\"http://schemas.xmlsoap.org/soap/envelope/\" ";

           sAXLRequest += "xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\"> ";

           sAXLRequest += "<SOAP-ENV:Body> <axl:getPhone xmlns:axl=\"http://www.cisco.com/AXL/1.0\" ";

           sAXLRequest += " xsi:schemaLocation=\"http://www.cisco.com/AXL/1.0 http://ccmserver/schema/axlsoap.xsd\" ";

           sAXLRequest += "sequence=\"1234\"> <phoneName>SEP222222222245</phoneName> ";

           sAXLRequest += "</axl:getPhone> </SOAP-ENV:Body> </SOAP-ENV:Envelope>";

          

           // finish the HTTPS Header

           sAXLSOAPRequest += sAXLRequest.length();

           sAXLSOAPRequest += "\r\n\r\n";

          

           // now add the SOAP payload to the HTTPS header, which completes the AXL SOAP request

           sAXLSOAPRequest += sAXLRequest;

          

           // now that the message has been built, we can connect to server and send it

           try

           {

                  socket = new Socket("localhost", 80);

                 

                  out = socket.getOutputStream();

                  in = socket.getInputStream();

                 

                  // send the request to the host

                  out.write(sAXLSOAPRequest.getBytes());

     

                  // read the response from the host

                  StringBuffer sb = new StringBuffer(2048);

                  bArray = new byte[2048];

                  int ch = 0;

                  int sum = 0;

                  while ( (ch = in.read(bArray)) != -1 )

                  {

                         sum += ch;

                         sb.append(new String(bArray, 0, ch));                 

                  }

                 

                  socket.close();

                  // output the response to the standard out

                  System.out.println(sb.toString());

                 

           } catch (UnknownHostException e)

           {

                  System.err.println("Error connecting to host: " + e.getMessage());

                  return;

           } catch (IOException ioe)

           {

                  System.err.println("Error sending/receiving from server: " + ioe.getMessage());

                 

                  // close the socket

                  try

                  {

                         if (socket != null) socket.close();

                  } catch (Exception exc)

                  {

                         System.err.println("Error closing connection to server: " + exc.getMessage());

                  }

                  return;

           }

    25.0 Attachments

    25.1 Document Review Action Item